package com.google.code.stalkernet.async;

/**
 * Base interface for interfaces featuring asynchronous operations.
 *
 * Typical declaration of asynchronous operation look like this:
 *
 * <pre>
 * public Handle asyncFoo (..., Callback &lt;T&gt; callback);
 * </pre>
 *
 * @author Mikhail Vladimirov
 */
public interface Async
{
    /**
     * Receives asynchronous operation result.
     *
     * @param <T> asynchronous operation result type
     */
    public interface Callback <T>
    {
        /**
         * Called when asynchronous operation completed successfully.
         *
         * @param result asynchronous operation result
         */
        public void onSuccess (T result);

        /**
         * Called when an error occurred while performing asynchronous
         * operation.
         *
         * @param error Throwable describing an error
         */
        public void onError (Throwable error);
    }

    /**
     * Handle of pending asynchronous operation.
     */
    public interface Handle
    {
        /**
         * Cancel pending asynchronous operation.
         *
         * @return <code>true</code> if operation was cancelled,
         *         <code>false</code> otherwise
         */
        public boolean cancel ();
    }
}
